PIC24F
RTCC Module Library Help


Table Of Contents

1     Library Features. 4

2     Using Library Functions in Your Code. 4

3     Functions. 4

3.1        RtccInitClock. 4

3.2        RtccReadAlrmDate. 5

3.3        RtccReadAlrmTime. 5

3.4        RtccReadAlrmTimeDate. 5

3.5        RtccReadDate. 5

3.6        RtccReadTime. 6

3.7        RtccReadTimeDate. 6

3.8        RtccSetAlarmRpt 6

3.9        RtccSetAlarmRptCount 6

3.10      RtccSetCalibration. 7

3.11      RtccSetChimeEnable. 7

3.12      RtccWriteAlrmDate. 7

3.13      RtccWriteAlrmTime. 8

3.14      RtccWrOn. 8

3.15      RtccWriteAlrmTimeDate. 8

3.16      RtccWriteDate. 9

3.17      RtccWriteTime. 9

3.18      RtccWriteTimeDate. 9

4     Macros. 10

4.1        mRtccIsWrEn() 10

4.2        mRtccWrOff() 10

4.3        mRtccIsOn() 10

4.4        mRtccOff() 10

4.5        mRtccOn() 11

4.6        mRtccIsAlrmEnabled() 11

4.7        mRtccAlrmEnable() 11

4.8        mRtccAlrmDisable() 11

4.9        mRtccIsSync() 11

4.10      mRtccWaitSync() 11

4.11      mRtccIs2ndHalfSecond() 12

4.12      mRtccClearRtcPtr() 12

4.13      mRtccSetRtcPtr(mask) 12

4.14      mRtccSetAlrmPtr() 12

4.15      mRtccClearAlrmPtr() 12

4.16      mRtccGetChimeEnable() 12

4.17      mRtccGetCalibration() 13

4.18      mRtccSetClockOe(enable) 13

4.19      mRtccSetInt(enable) 13

4.20      mRtccSetIntPriority(pri) 13

4.21      mRtccGetAlarmRpt() 13

4.22      mRtccGetAlarmRptCount() 13

4.23      mRtccGetCalibration() 14

 


1          Library Features

 

This peripheral library module:

 

·         Provides a Real-Time Clock and Calendar (RTCC) function.

·         Is intended for applications where accurate time must be maintained for extended periods of time with minimum to no intervention from the CPU.

·         Is optimized for low-power usage in order to provide extended battery lifetime while keeping track of time.

 

2          Using Library Functions in Your Code

 

Library routine parameters can be constructed using either AND based mask or AND_OR based mask setting. For more information on these masks, see 16-bit Peripheral Libraries.

 

Example of Use

 

#include “rtcc.h”

 

rtccTime RtccTime;  /* Initialize time struct with required values */

 

rtccTime RtccTimeVal; /* Initialize time struct with required values */

 

BOOL update_time;

BOOL update_alarm;

BOOL Time_Input_out_of_range;

 

void main(void)

{

   RtccInitClock();       //turn on clock source

   RtccWrOn();            //enable RTCC peripheral

   while(1)

   {

      /* Update the Time if requested */

      if(update_time)

      {

         Time_Input_out_of_range = (!RtccWriteTime(&RtccTime, TRUE));

         update_time = 0;

      }

      RtccReadTime(&RtccTimeVal);

 

      /*

        Supporting Application function / Code

      */

 

}//end RTCCModule

 

3          Functions

3.1         RtccInitClock

 

Function Prototype

void RtccInitClock(void);

Include

rtcc.h

Description

The function initializes the RTCC device. It starts the RTCC clock, sets the RTCC Off and disables RTCC write. Disables the OE.

Arguments

None

Return Value

None

Remarks:

None

Source File:

RtccInitClock.c

3.2         RtccReadAlrmDate

 

Function Prototype

void RtccReadAlrmDate (rtccDate* pDt);

Include

rtcc.h

Description

The function updates the user supplied union/structure with the current alarm Date of the RTCC device.

Arguments

pDt - pointer to a rtccDate union to store the alarm Date (rtccDate data type is defined in rtcc.h.)

Return Value

None

Remarks:

pDt must be a valid pointer.

Source File:

RtccReadAlrmDate.c

3.3         RtccReadAlrmTime

 

Function Prototype

void RtccReadAlrmTime (rtccTime* pTm);

Include

rtcc.h

Description

The function updates the user supplied union/structure with the current alarm time of the RTCC device.

Arguments

pTm - pointer to a rtccTime union to store the alarm time (rtccTime data type is defined in rtcc.h.)

Return Value

None

Remarks:

pTm must be a valid pointer.

Source File:

RtccReadAlrmTime.c

3.4         RtccReadAlrmTimeDate

 

Function Prototype

void RtccReadAlrmTimeDate(rtccTimeDate* pTD);

Include

rtcc.h

Description

The function updates the user supplied union/structure with the current alarm time and date of the RTCC device.

Arguments

pTD - pointer to a rtccTimeDate union to store the alarm time and date (rtccTimeDate data type is defined in rtcc.h.)

Return Value

None

Remarks:

pTD must be a valid pointer.

Source File:

RtccReadAlrmTimeDate.c

3.5         RtccReadDate

 

Function Prototype

void RtccReadDate(rtccDate* pDt);

Include

rtcc.h

Description

The function updates the user supplied union/structure with the current time of the RTCC device.

Arguments

pDt - pointer to a rtccDate union to store the current time (rtccDate data type is defined in rtcc.h.)

Return Value

None

Remarks:

The function makes sure that the read value is valid. It avoids waiting for the RTCSYNC to be clear by performing successive reads.

Source File:

RtccReadDate.c

3.6         RtccReadTime

 

Function Prototype

void RtccReadTime(rtccTime* pTm);

Include

rtcc.h

Description

The function updates the user supplied union/structure with the current time of the RTCC device.

Arguments

pTm - pointer to a rtccTime union to store the current time (rtccTime data type is defined in rtcc.h.)

Return Value

None

Remarks:

The function makes sure that the read value is valid. It avoids waiting for the RTCSYNC to be clear by performing successive reads.

Source File:

RtccReadTime.c

3.7         RtccReadTimeDate

 

Function Prototype

void RtccReadTimeDate(rtccTimeDate* pTD)

Include

rtcc.h

Description

The function updates the user supplied union/structure with the current time and date of the RTCC device.

Arguments

pTD - pointer to a rtccTimeDate union to store the current time and date (rtccTimeDate data type is defined in rtcc.h.)

Return Value

None

Remarks:

This firmware solution would consist of reading each register twice and then comparing the two values. If the two values match, then a rollover did not occur.

Source File:

RtccReadTimeDate.c

3.8         RtccSetAlarmRpt

 

Function Prototype

void RtccSetAlarmRpt(rtccRepeat rpt, BOOL dsblAlrm)

Include

rtcc.h

Description

The function sets the RTCC alarm repeat rate. rpt has to be a proper rtccRepeat enumeration value.

Arguments

rpt - value of the desired alarm repeat rate.

dsblAlrm  - if TRUE, the API can temporarily disable the alarm when changing the RPT value.

Return Value

None

Remarks:

If alarm is enabled, changing the repeat rate can be safely made only when the sync pulse is unasserted. To avoid waiting for the sync pulse, the user can choose to temporarily disable the alarm and then re-enable it. This means that the user has the knowledge that an alarm event is not imminent.

Source File:

RtccSetAlarmRpt.c

3.9         RtccSetAlarmRptCount

 

Function Prototype

void RtccSetAlarmRptCount(int rptCnt, BOOL dsblAlrm)

Include

rtcc.h

Description

The function sets the RTCC alarm repeat rate. rpt has to be a proper rtccRepeat enumeration value.

Arguments

rptCnt - value of the desired alarm repeat count (has to be a value less then 255).

dsblAlrm  - if TRUE, the API can temporarily disable the alarm when changing the RPT value.

Return Value

None

Remarks:

If alarm is enabled, changing the repeat count can be safely made only when the sync pulse is unasserted. To avoid waiting for the sync pulse, the user can choose to temporarily disable the alarm and then re-enable it. This means that the user has the knowledge that an alarm event is not imminent.

Source File:

RtccSetAlarmRptCount.c

3.10     RtccSetCalibration

 

Function Prototype

void RtccSetCalibration(int drift)

Include

rtcc.h

Description

The function updates the value that the RTCC uses in the auto-adjust feature, once every minute. The drift value acts as a signed value, [-128*4, +127*4], 0 not having any effect.

Arguments

drift - value to be added/subtracted to perform calibration drift has to fit into signed 8 bits representation

Return Value

None

Remarks:

Writes to the RCFGCAL.CAL[7:0] register should  only occur when the timer is turned off or immediately or after the edge of the seconds pulse (except when SECONDS=00 - due to the possibility of the auto-adjust event). In order to speed-up the process, the API function performs the reading of the HALFSEC field. The function may block for half a second, worst case, when called at the start of the minute. Interrupts can not be disabled for such a long period. However, long interrupt routines can interfere with the proper functioning of the device. Care must be taken.

Source File:

RtccSetCalibration.c

3.11     RtccSetChimeEnable

 

Function Prototype

void RtccSetChimeEnable(BOOL enable, BOOL dsblAlrm)

Include

rtcc.h

Description

The function enables/disables the chime alarm of the RTCC device.

Arguments

enable - boolean to enable/disable the RTCC chime.

dsblAlrm - if TRUE, the API can temporarily disable the alarm when changing the Chime status.

Return Value

None

Remarks:

If alarm is enabled, changing the chime status can be safely made when the sync pulse is unasserted. To avoid waiting for the sync pulse, the user can choose to temporarily disable the alarm and then re-enable it. This means that the user has knowledge that an alarm event is not imminent.

Source File:

RtccSetChimeEnable.c

3.12     RtccWriteAlrmDate

 

Function Prototype

void RtccWriteAlrmDate(const rtccDate* pDt)

Include

rtcc.h

Description

The function sets the alarm date in the RTCC device.

Arguments

pDt - pointer to a constant rtccDate union (rtccDate data type is defined in rtcc.h.)

Return Value

None

Remarks:

pDt a valid rtccDate pointer having proper values:

- wday: BCD codification, 00-06

- mday: BCD codification, 01-31

- mon : BCD codification, 01-12

The write is successful only if Wr Enable is set. The function will enable the write itself, if needed. Also, the Alarm will be temporarily disabled in order to safely perform the update of the ALRMTIME register. However, the device status will be restored. Note that the alarm date does not contain a year field.

Source File:

RtccWriteAlrmDate.c

3.13     RtccWriteAlrmTime

 

Function Prototype

void RtccWriteAlrmTime(const rtccTime* pTm)

Include

rtcc.h

Description

This function sets the current time in the RTCC device.

Arguments

pTm - pointer to a constant rtccTime union (rtccTime data type is defined in rtcc.h.)

Return Value

None

Remarks:

pTm a valid rtccTime pointer having proper values:

- sec : BCD codification, 00-59

- min : BCD codification, 00-59

- hour: BCD codification, 00-24

The write is successful only if Wr Enable is set. The function will enable the write itself, if needed.

Source File:

RtccWriteAlrmTime.c

3.14     RtccWrOn

 

Function Prototype

void RtccWrOn(void)

Include

rtcc.h

Description

Function to set the RCFGCAL.RTCWREN bitfield.

Arguments

None

Return Value

None

Remarks:

The interrupts are disabled in order to have a proper device initialization

Source File:

RtccWrOn.c

 

3.15     RtccWriteAlrmTimeDate

 

Function Prototype

void RtccWriteAlrmTimeDate(const rtccTimeDate* pTD)

Include

rtcc.h

Description

The function sets the current alarm time and date in the RTCC device.

Arguments

pTD - pointer to a constant rtccTimeDate union (rtccTimeDate data type is defined in rtcc.h.)

Return Value

None

Remarks:

rtccTimeDate structure fields have to have proper values:

- sec : BCD codification, 00-59

- min : BCD codification, 00-59

- hour: BCD codification, 00-24

- wday: BCD codification, 00-06

- mday: BCD codification, 01-31

- mon : BCD codification, 01-12

Note that the alarm time does not contain a year field.

Source File:

RtccWriteAlrmTimeDate.c

3.16     RtccWriteDate

 

Function Prototype

BOOL RtccWriteDate(const rtccDate* pDt, BOOL di)

Include

rtcc.h

Description

The function updates the user supplied union/structure with the current time and date of the RTCC device.

Arguments

pDt - pointer to a constant rtccDate union (rtccDate data type is defined in rtcc.h.)

di - if interrupts need to be disabled.

Return Value

TRUE '1' : If all the values are within range.

FALSE '0' : If any value is out of above mentioned range.

Remarks:

pDt is a valid rtccDate pointer having proper values:

 - wday: BCD codification, 00-06

 - mday: BCD codification, 01-31

 - mon : BCD codification, 01-12

 - year: BCD codification, 00-99

The write is successful only if Wr Enable is set. The function will enable the write itself, if needed. Also, the Alarm will be temporarily disabled and the device will be stopped (On set to 0) in order to safely perform the update of the RTC time register. However, the device status will be restored. Usually the disabling of the interrupts is desired, if the user has to have more precise control over the actual moment of the time setting.

Source File:

RtccWriteDate.c

3.17     RtccWriteTime

 

Function Prototype

BOOL RtccWriteTime(const rtccTime* pTm, BOOL di)

Include

rtcc.h

Description

The function updates the user supplied union/structure with the current time and date of the RTCC device.

Arguments

pTm - pointer to a constant rtccTime union (rtccTime data type is defined in rtcc.h.)

di - if interrupts need to be disabled.

Return Value

TRUE '1' : If all the values are within range.

FALSE '0' : If any value is out of above mentioned range.

Remarks:

pTm pointing to a valid rtccTime structure having proper values:

- sec : BCD codification, 00-59

- min : BCD codification, 00-59

- hour: BCD codification, 00-24

The write is successful only if Wr Enable is set. The function will enable the write itself, if needed.  Also, the Alarm will be temporarily disabled and the device will be stopped (On set to 0) in order to safely perform the update of the RTC time register. However, the device status will be restored.  Usually the disabling of the interrupts is desired, if the user has to have more precise control over the actual moment of the time setting.

Source File:

RtccWriteTime.c

3.18     RtccWriteTimeDate

 

Function Prototype

BOOL RtccWriteTimeDate(const rtccTimeDate* pTD)

Include

rtcc.h

Description

The function updates the user supplied union/structure with the current time and date of the RTCC device.

Arguments

pTD - pointer to a rtccTimeDate union to store the current time and date (rtccTimeDate data type is defined in rtcc.h.)

di - if interrupts need to be disabled

Return Value

TRUE '1' : If all the values are within range.

FALSE '0' : If any value is out of above mentioned range.

Remarks:

rtccTimeDate structure fields have to have proper values:

- sec : BCD codification, 00-59

- min : BCD codification, 00-59

- hour: BCD codification, 00-24

- wday: BCD codification, 00-06

- mday: BCD codification, 01-31

- mon : BCD codification, 01-12

- year: BCD codification, 00-99

The write is successful only if Wr Enable is set. The function will enable the write itself, if needed. Also, the Alarm will be temporarily disabled and the device will be stopped (On set to 0) in order to safely perform the update of the RTC time register. However, the device status will be restored. Usually the disabling of the interrupts is desired, if the user has to have more  precise control over the actual moment of the time setting.

Source File:

RtccWriteTimeDate.c

 

4          Macros

4.1         mRtccIsWrEn()

 

Macro

mRtccIsWrEn()

Include

rtcc.h

Description

Returns the value of RCFGCAL.RTCWREN.

Arguments

None

Remarks

None

4.2         mRtccWrOff()

 

Macro

mRtccWrOff()

Include

rtcc.h

Description

Macro to to clear the RCFGCAL.RTCWREN

Arguments

None

Remarks

None

4.3         mRtccIsOn()

 

Macro

mRtccIsOn()

Include

rtcc.h

Description

Returns the value of RCFGCAL.RTCEN.

Arguments

None

Remarks

None

4.4         mRtccOff()

 

Macro

mRtccOff()

Include

rtcc.h

Description

Macro to turn the RTCC off.

Arguments

None

Remarks

None

4.5         mRtccOn()

 

Macro

mRtccOn()

Include

rtcc.h

Description

Macro helper to turn the RTCC on.

Arguments

None

Remarks

Setting RCFGCAL.RTCEN to 1 clears the RTCWREN, RTCSYNC,

HALFSEC, RTCOE and the ALCFGRPT register.

4.6         mRtccIsAlrmEnabled()

 

Macro

mRtccIsAlrmEnabled()

Include

rtcc.h

Description

Returns the value of ALCFGRPT.ALRMEN

Arguments

None

Remarks

None

4.7         mRtccAlrmEnable()

 

Macro

mRtccAlrmEnable()

Include

rtcc.h

Description

Macro to set the ALCFGRPT.ALRMEN.

Arguments

None

Remarks

None

4.8         mRtccAlrmDisable()

 

Macro

mRtccAlrmDisable()

Include

rtcc.h

Description

Macro to clear the ALCFGRPT.ALRMEN.

Arguments

None

Remarks

None

4.9         mRtccIsSync()

 

Macro

mRtccIsSync()

Include

rtcc.h

Description

Macro read the status of the sync signal.

TRUE if sync asserted, FALSE otherwise

Arguments

None

Remarks

None

4.10     mRtccWaitSync()

 

Macro

mRtccWaitSync()

Include

rtcc.h

Description

Macro to wait until RCFGCAL.RTCSYNC signals read/write is safe.

Arguments

None

Remarks

In order to be sure that the write/read op is safe, interrupts should be disabled or kept very short (worst case scenario, sync can be asserted for 32 RTCC clocks, i.e. almost 1ms, so it is not advisable to disable the interrupts for such a long period of time. Care must be taken under these circumstances).

4.11     mRtccIs2ndHalfSecond()

 

Macro

mRtccIs2ndHalfSecond()

Include

rtcc.h

Description

Reads the half-second status bit.

TRUE if it's the second half period of a second; FALSE otherwise.

Arguments

None

Remarks

None

4.12     mRtccClearRtcPtr()

 

Macro

mRtccClearRtcPtr()

Include

rtcc.h

Description

Clears the RTCC Value Register Window Pointer bits.

Arguments

None

Remarks

It sets the pointer to the min/sec slot.

4.13     mRtccSetRtcPtr(mask)

 

Macro

mRtccSetRtcPtr(mask)

Include

rtcc.h

Description

Set the RTCC Value Register Window Pointer bits to the desired value.

Arguments

mask - value of the pointer mask enum RTCCPTR_MASK defined in rtcc.h. mask has to be valid member of RTCCPTR_MASK.

Remarks

Macro mRtccClearRtcPtr() must be called prior to this macro.

4.14     mRtccSetAlrmPtr()

 

Macro

mRtccSetAlrmPtr()

Include

rtcc.h

Description

Macro to set the Alarm Value Register Window Pointer bits.

Arguments

None

Remarks

It sets the pointer to the slot beyond the ALRMDAY. Macro mRtccClearAlrmPtr() must be called prior to this macro.

4.15     mRtccClearAlrmPtr()

 

Macro

mRtccClearAlrmPtr()

Include

rtcc.h

Description

Macro to clear the Alarm Value Register Window Pointer bits.

Arguments

None

Remarks

It sets the pointer to the slot beyond the ALRMDAY.

4.16     mRtccGetChimeEnable()

 

Macro

mRtccGetChimeEnable()

Include

rtcc.h

Description

Returns the chime alarm of the RTCC device.

Arguments

None

Remarks

None

4.17     mRtccGetCalibration()

 

Macro

mRtccGetCalibration()

Include

rtcc.h

Description

Returns the value that the RTCC uses in the auto-adjust feature, once every minute.

Arguments

None

Remarks

The calibration value is a signed 10 bits value, [-512, +511].

4.18     mRtccSetClockOe(enable)

 

Macro

mRtccSetClockOe(enable)

Include

rtcc.h

Description

Enables/disables the Output Enable pin of the RTCC.

Arguments

enable - the desired status of the Output Enable pin.

Remarks

None

4.19     mRtccSetInt(enable)

 

Macro

mRtccSetInt(enable)

Include

rtcc.h

Description

Enables/disables the RTCC event interrupts.

Arguments

enable - enable/disable the interrupt.

Remarks

None

4.20     mRtccSetIntPriority(pri)

 

Macro

mRtccSetIntPriority(pri)

Include

rtcc.h

Description

Sets the RTCC event interrupt priority.

Arguments

pri - the interrupt priority.

Remarks

None

4.21     mRtccGetAlarmRpt()

 

Macro

mRtccGetAlarmRpt()

Include

rtcc.h

Description

The macro returns the current RTCC alarm repeat rate.

Arguments

None

Remarks

None

4.22     mRtccGetAlarmRptCount()

 

Macro

mRtccGetAlarmRptCount()

Include

rtcc.h

Description

The macro reads the RTCC alarm repeat counter.

Arguments

None

Remarks

None

4.23     mRtccGetCalibration()

 

Macro

mRtccGetCalibration()

Include

rtcc.h

Description

The macro returns the value that the RTCC uses in the auto-adjust feature, once every minute.

Arguments

The calibration value is a signed 10 bits value, [-512, +511].

Remarks

None